Merciful 4/Merciful - Disc 4.iso/software/p/psychotoads.dms/psychotoads.adf/a56

Text File | 1989-03-31 | 26KB | 860 lines

                            5: STRING FUNCTIONS                             54
                       -----------------------------


         =LEFT$= (return the leftmost characters of a string)

d$=LEFT$(s$,n)

This instruction works like in nearly any Basic language (for example,
AmigaBasic). Example:

        B$="Hello! This is Ronnie!"
        L$=Left$(B$,9)
        Print L$
( result: Hello! Th )



         =RIGHT$= (return the rightmost character of a string)


d$=RIGHT$(s$,n)

Same as the LEFT$ -instruction, but takes the rightmost characters.

        Print Right$("AMOS Basic",5)
( result: Basic )



      =MID$= (return a string of characters from within a string)           55

d$=MID$(s$,p,n)
MID$(d$,p,n)=s$

The MID$ function returns the middle section of the string held in s$.
p denotes the offset of characters to the start of this substring, and
n holds the number of characters to be fetched. If a value of "n" is
not specified in the instruction then the characters will be read right
up to the end of your string. Example:

        Print Mid$("AMOS Basic",6)
( result: Basic )

There is also a MID$ instruction:

        MID$(d$,p,n)=s$

This version of MID$ loads "n" characters into d$ starting from
position p+1 in s$. If a value of n is not specified directly then
characters will be replaced up to the end of the source string s$. This
kind of instruction is also possible when using LEFT$ and RIGHT$.
Here's an example:

        A$="AMOS *****"
        Mid$(A$,5)="Magic"
        Print A$
( result: AMOS Magic )



                 =INSTR (search for occurrences of a                        56
                     string within another string)

f=INSTR(d$,s$ [,p])

INSTR allows you to search for all occurrences of one string inside
another. It is often used in adventure games to split a complete line
of text into its individual commands. There are two possible formats of
the INSTR function.

f=INSTR(d$,s$)

This searches for the first occurrence of s$ in d$. If the string is
found then its position will be returned directly, otherwise the result
will be set to zero. Examples:

        Print Instr("AMOS BASIC","AMOS")
( result: 1 )
        Print Instr("AMOS BASIC","S")
( result: 4 )
        Print Instr("AMOS BASIC","AMIGA")
( result: 0 )


        Do
          Input "String to be searched";D$
          Input "String to be found";S$
          X=Instr(D$,S$)
          If X=0 Then Print S$;" Not found"
          If X<>0 Then Print S$;" Found at position ";X
        Loop

Normally the search will commence from the first character in your text
string (d$). The secont version of INSTR lets you test a specific
section in the string at a time.

  p is now the position of the beginning of your search. All characters
are numbered from the left to right starting from zero. Therefore p
ranges from 0 to LEN(s$). Example:

        Print Instr("AMOS BASIC","S",5)
( result: 8)



           =UPPER$ (convert a string of text to upper case)                 57

s$=UPPER$(n$)

This function converts the string in n$ into upper case (capitals) and
places the result into s$. Example:

        Print Upper$("AmOs BaSic")
( result: AMOS BASIC )



               =LOWER$ (convert a string to lower case)

s$=LOWER$(n$)

LOWER$ translates all the characters in n$ into lower case. This is
especially useful in adventure games, as you can convert all the user's
input into a standard format which is much easier to interpret.
Example:

        Input "Continue (Yes/No)";ANSWER$
        ANSWER$=Lower$(ANSWER$) : If ANSWER$="no" Then Edit
        Print "Continuing with your prog..."



                       =FLIP$ (invert a string)

f$=FLIP$(n$)

FLIP$ simply reverses the order of the characters held in n$.



                     =SPACE$ (space out a string)

s$=SPACE$(n)

Generates a string of n spaces and places them into s$. Example:

        Print "Twenty" ; Space$(20); "spaces"



                 =STRING$ (create a string full of a$)                      58

s$=STRING$(a$,n)

STRING$ returns a string with n copies of the first character in a$:

        Print String$("The cat sat on the mat",10)
( result: TTTTTTTTTT )



                    =CHR$ (return Ascii character)

s$=CHR$(n)

Creates a string containing a single character with Ascii code n.



                 =ASC (get Ascii code of a character)

c=ASC(a$)

ASC supplies you with the internal Ascii code of the first character in
the string a$:

        Print Asc("B")
( result: 66 )



         =LEN (returns the number of characters stored in a$)

This way you can get the length of a string:

        Print Len("12345678")
( result: 8 )



                   =VAL (convert a string to number)                        59

v=VAL(x$)
v#=VAL(x$)

VAL converts a list of decimal digits stored in x$ into a number. If
this process fails for some reason, a value of zero will be returned
instead. Example:

        X=Val("1234):Print X
( result: 1234 )



                 =STR$ (convert a number to a string)

s$=STR$(n)

STR$ converts an integer variable into a string. This can be very
useful because some functions, such as CENTRE, do not allow you to
enter numbers as a parameter. Example:

        Centre "Memory left is "+Str$(Chip Free)+" Bytes."

Do not confuse STR$ with STRING$.



Array options
=============


                 SORT (sort all elements in an array)

SORT a(0)
SORT a#(0)         The SORT instruction arranges the contents of any
SORT a$(0)         array into ascending order. This array can contain
                   either strings, integers, or floating point numbers.
The a$(0) parameter specifies the starting point of your table. It must
always be set to the first item in the array (item number 0). Example:

        Dim A(25)
        P=0
        Repeat
          Input "Input a number (0 to stop)";A(P)
          Inc P
        Until A(P-1)=0 Or P>25
        Sort A(0)
        For I=0 to P-1
          Print A(I)
        Next



                        MATCH (search an array)                             60

r=MATCH(t(0),s)
r=MATCH(t#(0),s#)     MATCH searches through a sorted array for the
r=MATCH(t$(0),s$)     value s. If this is succesfully found then r
                      will be negative. Taking the absolute value of
this figure will provide you with the item which came closest to your
original search parameter.

  Note that only arrays with a single dimension can be checked in this
way. You'll also need to sort the array with SORT before calling this
function. Example:

        Read N
        Dim D$(N)
        For I=1 to N
          Read D$(I)
        Next I
        Sort D$(0)
        Do
          Input A$
          If A$="L"
            For I=1 to N:Print D$(I):Next I
          Else
            POS=Match(D$(0),A$)
            If POS>0 Then Print "Found",D$(POS);" In Record ";POS
            If POS<0 And Abs(POS)<=N Then Print A$,"Not Found. Closest
                                                     To ",D$(Abs(POS))
            If POS<0 And Abs(POS)>N Then Print A$, "Not Found. Closest
                                                            To ";D$(N)
          Endif
        Loop
        Data 10,"Adams","Asimov","Shaw","Heinlien","Zelazny","Foster"
        Data "Niven","Harrison","Pratchet","Dickson"

Note that MATCH could be used in conjunction with the INSTR function to
provide a powerful parser routine. This might be used to interpret the
instructions you entered in an adventure game.







                              6:GRAPHICS                                    61
                     -----------------------------

AMOS Basic provides you with everything you need to generate some
amazing graphics. There's a comprehensive set of commands for drawing
rectangles, circles and polygons. As you would expect from the Amiga,
all operations are performed practically instantaneously. But even here
AMOS Basic has a trick or two up its sleeve.

  The AMOS graphical functions work equally well in all the Amiga's
graphics modes INCLUDING hold and modify mode (HAM). It's therefore
possible to create breathtaking HAM pictures directly within AMOS
Basic!

  Furthermore, you're not just limited to the visible screen. If you've
created an extra large playing area, you'll be able to access every
part of your display using the standard drawing routines. So it's easy
to generate the scrolling backgrounds required by arcade games such as
Defender.


Colours
-------
The Amiga allows you to display up to 64 colours on the screen at a
time. These colours can be selected using the INK,COLOUR and PALETTE
commands.



              INK (set colour used by drawing operations)

INK col[,paper][,border]

"col" specifies the colour which is to be used for all subsequent
drawing operations. The colour of every point on the screen is taken
from one of 32 different colour registers. These registers can be
individually set with a colour value chosen from a palette of 4096
colours.

  Although the Amiga only provides you with 32 actual color registers,
AMOS lets you use colour numbers ranging from 0 to 63. This allows you
to make full use of the colours available from the Half-Bright and HAM
modes respectively. A detailed explanation of these modes can be found
in the Screens chapter.

  The "paper" colour sets the background colour fill patterns generated
by the SET PATTERN command.

  The "border" colour selects an outline colour for your bars and
polygons. This option can be activated using the SET PAINT command like
so:

        Set pattern 0 : Set paint 1
        Repeat
          C=Rnd(16):Ink 16-C,0,C
          X=Rnd(320)-20:Y=Rnd(200)-20:S=Rnd(100)+10
          Bar X,Y to X+S,Y+S
        Until Mouse Key

Note that any of the parameters col, paper and border, may be omitted.
Simply include "empty" commas at the appropriate places in the
instruction. For example:

        Ink ,,5 : Rem  Just sets the border colour



                  COLOUR (assign a colour to an index)                      62

COLOUR index,$RGB

The COLOUR instruction allows to assign a colour to each of the Amiga's
32 colour registers.

  "Index" is the number of the colour you wish to change, and can range
from 0-31. As you may know, any colour can be created by mixing
specific amounts of the primary colours Red, Green and Blue. The shade
of your colour is completely determined by the relative intensities of
the three components

  The expression $RGB consists of three digits from 0 to F. Each
component sets the strength of one of the primary colours, Red (R),
Green (G) or Blue (B). The size of the components is directly
proportional to the brightness of the associated colour. So the higher
values, the brighter the eventual colour.

        Hex Digit   0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
        Decimal     0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15

HAM and Extra Half-Bright modes use these indices slighty differently.
See Chapter 9 for more details.



                 =COLOUR (read the colour assignment)

c=COLOUR(index)

The COLOUR function takes an index number from 0 to 31, and returns the
coour value which has been previously assigned to it.
  "Index" is simply the colour number whose shade you wish to
determine. You can use this function to produce a list of the current
colour settings of your Amiga like so:

        For C=0 To 15
          Print Hex$(Colour(C),3)
        Next C



               PALETTE (set the current screen colours)                     63

PALETTE list of colours

The PALETTE instruction is really just a rather more powerful version
of COLOUR. Instead of loading the colour values one at a time, the
PALETTE command allows you to install a whole new palette of colours in
a single statement.

        However you don't have to set all the colours in the palette at
once. Any combination of colours can be loaded individually ;

        PALETTE $100,$200,$300 : Rem Sets just three colours

You can also change selected colours in the middle of your list ;

        PALETTE $200,,$400 : Rem Change colours 0 and 2

It's important to realise that only the colours in the palette which
are specifically set by this command will actually be changed. All
other colours will retain their original values. Here are some
examples:

        Palette 0,$F00,$0F0
        Palette 0,$770
        Palette 0,,$66
        Palette 0,$1,$2,$3,$4,$5,$6,$7,$8,$9,$A,$B,$C,$D,$E,$F

At the start of your program the colour palette is automatically loaded
using a list of default color values. These settings can be adjusted
using a simple option from the AMOS configuration program.

  This command can also be used to set the colours used by the
Half-Bright and HAM modes. These extend the existing colour palette to
generate dozends of extra colours on the screen. See chapter 10...



Line drawing commands
=====================


                 GR LOCATE (position graphics cursor)

GR Locate x,y

This sets the position of the graphics cursor to screen coordinates
x,y. The graphics cursor is used as the default starting point for most
drawing operations. So if you omit the coordinates from commands such
as PLOT or CIRCLE, the objects will be drawn at the current cursor
position. For example:

        Gr Locate 10,10 : Plot ,
        Gr Locate 100,100 : Circle ,,100



               =XGR (return x coordinate of gfx cursor)                     64
               =YGR (return y coordinate of gfx cursor)

x=XGR
y=YGR

These functions return the present coordinates of the graphics cursor:

        Circle 10,100,100
        Print Xgr,Ygr



                      PLOT (plot a single point)

PLOT x,y [,c]

The PLOT command is the simplest drawing function provided by AMOS
Basic. It plots a point at coordinates x,y using colour c. The new ink
colour will now be used in all subsequent drawing operations.

  If the colour "c" is omitted from this instruction, the point will be
plotted in the current colour. For example:

        Curs Off: Flash Off : Randomize Timer
        Do
          Plot Rnd(319),Rnd(199),Rnd(15)
        Loop

It's also possible to omit the X or Y coordinates from this
instruction. The point will be plotted at the gfx cursor position.

        Plot 100,100,4
        Plot ,150
        Cls : Plot ,



                   POINT (get the colour of a point)

c=POINT(x,y)

POINT returns the colour index of a point at coordinates x,y ;

        Plot 100,100
        Print "The colour at 100,100 is ";Point(100,100)



                          DRAW (draw a line)6                               65

DRAW is another very Basic instruction. Its action to draw a simple
straight line on the Amiga's screen.

        DRAW x1,y1 TO x2,y2

Draws a line between the coordinates x1,y1 and x2,y2

        DRAW TO x3,y3

Draw a line from the current gfx crsr position to x3,y3. Example:

        Colour 4,$707:Ink 4
        Draw 0,50 To 200,50
        Draw To 100,100
        Draw To 0,50



                     BOX (draw a hollow retangle)

BOX x1,y1 TO x2,y2

The BOX command draws a hollow retangular box on the screen. x1,y1 are
the coordinates of the top left corner of the box, and x2,y2 are the
coordinates of the point diagonally opposite.



                   POLYLINE (multiple line drawing)

POLYLINE is very similar to DRAW except that it draws several lines at
a time. It's capable of generating complex hollow polygons in just a
single statement.

        POLYLINE x1,y1 TO x2,y2 TO x3,y3



                     CIRCLE (draw a hollow circle)                          66

CIRCLE x,y,r

The Circle command draws a hollow circle with radius r and centre x,y.

As normal, if the coordinates are omitted from this command, the circle
will be drawn from the current cursor position;

        Plot 100,100 : Circle ,,50



                    ELLIPSE (draw a hollow ellipse)

ELLIPSE x,y,r1,r2

The ELLIPSE instruction draws a hollow ellipse at coordinates x,y. The
horizontal radius is r1. It corresponds to exactly half the width of
the ellipse. r2 is the vertical radius and is used to set the height of
the ellipse. The total height of the ellipse is r*2


Line types                                                                  67
----------
AMOS Basic allows you to draw your lines using a vast range of possible
line styles.



                    SET LINE (set the line styles)

SET LINE mask

The SET LINE command sets the style of all lines which are subsequently
drawn using the DRAW, BOX and POLYLINE commands.

  "Mask" is a 16-bit binary number which describes the precise
appearance of the line. Any points in the line which are to be
displayed in the current ink colour are represented by a one, and any
points which are to be set to the background colour are indicated by a
zero. So a normal line is denoted by the binary number
%1111111111111111 and will be displayed as _______. Similarly, a dotted
line like _ _ _ _ will be produced by a mask of %1111000011110000.

  By setting the line mask to values between 0 and 65535, it is
possible to generate a great variety of different line types ;

        Set Line $F0F0
        Box 50,100 To 150,150

This line style as no effect on shapes drawn with CIRCLE or ELLIPSE.



Filled shapes
=============


                         PAINT (contour fill)

PAINT x,y,mode

The PAINT command allows you to fill any region on the screen with a
solid block of colour. Additionally you can select a fill pattern for
your shapes using the SET PATTERN command.

  x,y are the coordinates of a point inside the area to be filled.
"Mode" can be set to either 0 or 1. A value of 0 terminates the filling
operation at the first pixel found with the current border colour. A
mode of 1 halts the filling operation at any colour which is different
from the existing ink colour.

See EXAMPLE 6.1  in the MANUAL folder for a demonstration.



                     BAR (draw a filled rectangle)                          68

BAR x1,y1 TO x2,y2

Draws a filled bar from x1,y1 -the coordinates of the top left corner
of the bar- to x2,y2 -the opposite corner coordinates.



                    POLYGON (draw a filled polygon)

POLYGON x1, TO x2,y2 TO x3,y3 ...
POLYGON TO x1,y1 TO x2,y2 ...

POLYGON generates a filled polygon in the current ink colour It's
basically just a solid version of the standard POLYLINE command.
There's no real limit to the number of coordnate pairs you may use,
other than the maximum line length permitted by AMOS Basic (255 chars).



Fill types
----------
In AMOS Basic you're not just restricted to filling your shapes with a
solid block of colour. There are dozens of fill patterns to choose
from, and you can even load your own patterns directly from the sprite
bank.



                   SET PATTERN (select fill pattern)                        69

SET PATTERN pattern

This command allows you to select a fill pattern for use by your
drawing operations. There are three possibilities

        Pattern=0

This is the default, and fills your shapes with a solid block of the
current INK colour.

        Pattern>0

If the pattern number is >0, AMOS Basic selects on of 34 built-in fill
styles. These are found in the MOUSE.ABK file on your start-up disc,
and can be edited using the AMOS Basic sprite definer. Note that the
first three images in this files are required by the mouse cursor (see
CHANGE MOUSE). The fill patterns are stored in the images from four
onwards.

        Pattern<0

This is the most powerful option of all. "Pattern" now refers to a
sprite image in bank one. The image is number calculated using the
formula:  SPRITE IMAGE = PATTERN * (-1)

The selected image will be automatically truncated before use,
according to the following rules

 * The width of the image will be clipped to sixteen pixels
 * The height will be rounded to the nearest power of two, ie 1,2..,64

Depending on the type of your image, the pattern will be drawn in one
of two separate ways. Two-colour images are drawn in "monochrome". The
actual colours in your image are completely discarded, and the pattern
is drawn using the current ink and paper colours.

  It's also possible to produce multi-coloured fill patterns. In this
case the foreground colours of your image and merged with the current
ink colour using a logical AND. Similarly the paper colours of your
pattern is OR'ed with the sprite background (colour zero). If you wish
to use your original sprite colours, you'll need to set the ink and
background colours like so:

        Ink 31,0

Don't forget to load your sprite palette from the sprite bank with
GET SPRITE PALETTE before using these instructions, otherwise the
display is likely to look rather messy. Examples of this instruction
can be found in EXAMPLE 6.2  in the MANUAL folder.



                 SET PAINT (set / reset outline mode)                       70

SET PAINT n

Toggles the outline drawn by the POLYGON or BAR instructions. As a
default this mode is set to OFF.

  If n=1 then outline mode will be activated.



Writing styes
=============


                   GR WRITING (ghange writing mode)

GR WRITING bitpattern

Whenever you draw some graphics on the screen, you naturally assume
that anything underneath it will be overwriteen. The GR WRITING command
allows you to choose from a range of four alternative drawing modes.
These can used to generate dozens of intriguing effects.

  "Bitpattern" holds a sequence of binary bits which specify which
graphics mode you wish to use. Here's a list of the various
possibilities along with a brief explanation of their effects:

JAM1 mode (Bit 0=0)
                    JAM1 only draws the parts of your graphics which
are set to the current INK colour. Any sections drawn in the paper
colour are totally omitted. This is particularly useful with with the
TEXT command as it allows you to merge your text directly over an
existing screen background. For example:

        Ink 2,5:Text 140,80,"Normal Text":Gr Writing 0:
                                     Text 140,71,"JAM1"

JAM2 mode (Bit 0=1)
                    This is the default condition. Any existing
graphics on the screen will be completely replaced by your new image.


XOR mode (Bit 1=1)
                    XOR combines your new graphics with those already
on the screen using a logical operation known as eXclusive OR. The net
result is to change the colour of the areas of a drawing which overlap
an existing picture.

  One interesting side effect of XOR mode is that you can erase any
object from the screen by simply setting XOR mode and drawing your
object again at exactly the same position. EXAMPLE 6.3  contains a
simple demonstration of this technique and produces a neat rubber and
banding effect.


INVERSEVID (Bit 2=1)
                     This reverses the image before it is drawn. So any
sections of your image drawn in the ink colour will be replaced by the
current paper colour and vice-versa. INVERSEVID mode is often used to
produce inverted text.

  Since these modes are set using a bitpattern, it's possible to
combine several mode together.

        Gr Writing 4+1 : Rem set JAM2 and INVERSEVID
        Gr Writing 7   : Rem chooses JAM2,INVERSEVID and XOR
        Ink 2,5 : Text 140,80,"Accession & Image rulez!"

NOTE: This command only affects drawing operations such as CIRCLE, BOX
and graphical text (TEXT). The drawing mode used by normal text
commands like PRINT and CENTRE is set using a separate WRITING command.
See also AUTOBACK.



          CLIP (restrict all gfx to a section of the screen)                71

CLIP [x1,y1 TO x2,y2]

The CLIP instruction limits all drawing operations to a rectangular
region of the screen specified by the coordinates x1,y1 to x2,y2.

  x1,y1 represent the coordinates of the top left hand corner of the
rectangle, and x2,y2 hold the coordinates of the bottom right corner.

  Note that it's perfectly acceptable to use coordinates outside the
normal screen boundaries. All the clipping operations will work as
expected, even if only a section of the clipping rectangle is actually
visible.

  As you can see, only the parts of the circle which lie within the
clipping rectangle have been drawn on the screen. The clipping zone can
be restored to the normal screen area. by omitting all the coordinates
from this instruction.

  See EXAMPLE 6.4  in the MANUAL folder.



Advanced techniques
===================


                  SET TEMPRAS (set temporary raster)

SET TEMPRAS [address,size]

This instruction allows experienced Amiga programmers to fine tune the
amount of memory used by various graphics operations. WARNING:
improper use of this instruction can crash your Amiga copletely!

  Whenever an AMOS program performs a fill command, a special memory
area is reserved to hold the fill pattern. This memory is automatically
returned to the system after the instruction has been terminated. The
size of the memory buffer is equivalent to a single bit plane in the
current screen mode. So the default screen takes up to a total of 8k.

  The size and location of the graphics buffer can be changed at any        72
time using the SET TEMPRAS instruction.

  "Size" is the number of bytes you wish to reserve for your buffer
area. It ranges between 256 and 65536.

  The amount of memory required for a particular object can be
calculated in the following way:

        - Enclose the object to be drawn with a rectangular box
        - The area required will given by: Size=Width/8 * Height.

If you are intending to use the PAINT command, you should take care to
ensure that your figure is *closed*, otherwise more memory will be
neede and the system may crash.

  "Buffer" can be either an addess or a memory bank. The memory you
reserve for this buffer should always be CHIP ram. Since the buffer
area is now allocated once and for all at the start of your program,
there's no need to continually reserve and restore the memory buffer.
This can speed up the execution of your programs by up to 5 %.

  You can restore the buffer area to its original value by calling the
SET TEMPRAS command with no parameters.

  See the EXAMPLE 6.5  in the MANUAL folder.